Mac Format 1996 April

home *** CD-ROM | disk | FTP | other *** search

/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / Update History / Read Me! 2.5 -> 2.5.2 changes < prev next >

Wrap

Text File | 1994-09-17 | 19KB | 310 lines

Tools Plus Changes: 2.5 to 2.5.2 ~~~~~~~~~~~~~~~~~~~~~~~~~ Display this document in Geneva 12pt. You need to read this document if: √ You are upgrading from an older version of Tools Plus. If you are upgrading from a version older than 2.5, read all other applicable change documents first. √ If you have purchased Tools Plus 2.5.2 and it arrived with a Tools Plus 2.5 User Manual. Double-bullets (••) denote changes that are NOT in the printed manual. * * * W A R N I N G * * * THIS UPDATE INCLUDES REVISIONS THAT MAY REQUIRE YOU TO CHANGE PARTS OF YOUR EXISTING APPLICATION(S). PLEASE READ CAREFULLY. Tools Plus 2.5.2, released in September 1994, includes the following changes implemented since the previous version, 2.5.1: • Tools Plus 2.5.2 contains a new set of libraries and files. Replace your existing Tools Plus files with the new ones included in this update. Delete all your old copies of the Tools Plus libraries and related files (C header, Pascal interface etc.) • (C/C++ only) the PopUpStyle and MenuStyle routines now work correctly. They used to always set the style to “underline and outline” on some Macs. • Right-aligned and centered Editing Fields now scroll text into view correctly (we have replaced the default TextEdit scrolling routine with our own). • Text pasting has been accelerated when (i) you paste text that contains carriage returns into a field that disallows carriage returns, or (ii) you paste a lot of text into a length limited field. In previous versions you could see “character at a time” pasting. This was especially evident on slower Macs. • All editing fields now scroll and display better than ordinary TextEdit fields. When the cursor is dragged out of the editing field, the field’s text is automatically scrolled into view. The further the cursor is moved out of the field, the faster the text is scrolled. •• User Manual page 35 should contain the following _NEW_ information… You can optionally have Tools Plus position your window for you. The most common example of this is centering a modal dialog on the main monitor (perhaps to display a progress thermometer). You can also “tile” windows when you need to open multiple windows and you don’t want to calculate each window’s position. Window tiling calculates the new window’s position relative to the front most standard window (it is not useful for floating palettes or modal windows). To center or tile a window, add the wCenter or wTile constant to the window’s procID. The WindowOpen and WindowOpenRect now accept long (4 byte) integers for their procID. The constants which may be added to the window’s procID are: wCenter = $00010000; {auto-centering added to procID } wTile = $00020000; {auto-tiling added to procID } •• User Manual page 35 should contain the following _NEW_ information… In Tools Plus, you can make any window behave like a floating palette simply by adding the wPalette constant to the window’s procID (both paletteProc and altPaletteProc already include this option). This allows you to use third-party WDEFs for their appearance, while Tools Plus makes them behave like floating palettes. You can write your own WDEF for floating palettes, or you can use third-party WDEFs. As per Macintosh standards, a window’s procID is comprised from the following formula: WDEF ID x 16 + variant code. When you add the wPalette constant to the window’s procID, Tools Plus makes the window behave like a floating palette. wPalette = $80000000; {window behaves like palette (add } {this constant to procID) } •• User Manual page 83, 3rd paragraph should contain the following _NEW_ information… If a field’s height is less than or equal to its font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading ), and you disallow carriage return characters ($0D) in the field, the field is deemed to be a “single line field.” Word wrap does not occur in single line fields. Instead, the field’s text automatically scrolls to ensure that the selection always remains in view In prior versions, single line fields allowed the inclusion of carriage return characters. Fields whose text is centered can now be “single line”. • The Edit menu’s Undo…/Redo… command has been enhanced when working with Editing Fields. When you use “Undo…”, the field’s selection range (or insertion point) is set to the character(s) affected by the original operation. When you use “Redo…”, the field’s selection range (or insertion point) is set appropriately to reflect the completion of the operation (i.e., at the end of pasted or typed text). • (C/C++ only) The PascalStrHandles.c file (it contains routines used to copy a C string into a Pascal string handle, and vice versa) has been corrected to use an “unsigned char” for the Pascal string’s length byte (byte-0 in the string). Otherwise, strings over 127 characters long would not be copied correctly. •• (C/C++ only) The ToolsPlus.h header file has been updated to use a more correct C syntax in places where a Pascal var Str255 would have occurred. The example below illustrates the change: OLD: pascal void GetFieldString (Str255 *EditString); NEW: pascal void GetFieldString (Str255 EditString); The routines affected by this a change are: GetFieldString GetListBoxText GetMenuString GetPopUpString •• User Manual page 129, EnableMenu section should contain the following _NEW_ information… You can now disable and enable the entire Apple menu by using: EnableMenu(0, 0, disabled); or EnableMenu(0, 0, enabled); • When the user types a Command-key that does not match those in enabled menu items (or if menus are inaccessible because a modal window is displayed), the Command key is passed to your application by a doKeyDown or doAutoKey event. This is evident in modal windows because Tools Plus used to beep the user when a Command-key was typed. Now, the key is passed back to your application, and your application can elect to process the key or to beep the user. If a modal window has a “close box”, typing Command-W no longer results in a doGoAway event being reported for that window. • Tools Plus no longer uses the TEGetScrapLen routine, which has been obsoleted in newer MacTraps libraries (C/C++). In previous versions of Tools Plus, some C/C++ programmers had to use the “Old MacTraps” file in lieu of “MacTraps.” This is no longer the case. •• User Manual page 202, Wait section should be changed to note that the Wait routine now accepts a long (4 bytes) integer parameter. •• User Manual page 180, note that the polling record’s Poll.Event field is also populated by the doResume and doSuspend events. ------------------------------------------------------------ •• Handles to an Editing Field’s string ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Prior versions of Tools Plus did not allow odd length editing field strings (except for Str255). This was due to a carry-over from THINK Pascal which rounds string structures to even byte boundaries (i.e., a string[20] reserves 20 bytes for the characters, plus 1 length byte, then rounded up to 22 bytes). As a result of this rounding phenomenon, prior versions of Tools Plus would “round down” the logical length of a string (because a 14 character and 15 character field _both_ produced a 16 byte structure in THINK Pascal). To remedy this anomaly, a new NewStrHandle routine has been provided to let you create initialized string handles that are exactly the right size. C/C++ programmers can still opt to use the toolbox’s NewHandle routine in conjunction with the sizeof routine. You will probably have to modify your existing application(s) to use the NewStrHandle routine instead of NewHandle. Please add the following note to page 82 of the printed manual: Note: Your application must allocate memory for each handle that it provides to Tools Plus by using the NewHandle or Tools Plus’s NewStrHandle routine. Tools Plus does not automatically allocate this memory. If your editing fields contain random characters, it is a sure sign that you have not allocated memory for your handle. Please add the following new routine to page 87 of the printed manual: NewStrHandle ~~~~~~~~~~~ Allocate memory for a Pascal string, and initialize it to an empty string. pascal StringHandle NewStrHandle (short StringLen); function NewStrHandle (StringLen: INTEGER): STRINGHANDLE; StringLen is the size of the Pascal string (from 1 to 255 characters) being allocated. NewStrHandle automatically allocates one additional byte of heap memory to accommodate the entire Pascal string plus a length byte. The function’s value returns a string handle to a Pascal string of the specified length. The string is initialized to an empty string (‘’), thus making is ready for immediate use with the NewField or NewFieldRect routines. Please replace the third paragraph of the NewField description (on page 87 in the printed manual) with the following: HStr is a handle that provides this field with a reference to its string. The handle can be generic, but it’s treated like a string handle by Tools Plus, in that the first byte of its memory block is a length byte and the remainder is the actual string. A copy of the hStr handle’s contents is used while the field is being edited. It is also used to automatically display an inactive edit field’s text when a window needs to be refreshed. Each field must have its own string. You must allocate memory for the handle and set it to a default string value before using it in the NewField routine. A good way to both allocate and initialize the handle is to use the NewStrHandle routine. ------------------------------------------------------------ •• A new routine has been added (add to page 91) that lets your application determine if a field is empty without having to get its text. FieldIsEmpty ~~~~~~~~~~ Determine if the specified field is empty. pascal Boolean FieldIsEmpty (short Field); function FieldIsEmpty (Field: INTEGER): BOOLEAN; Field specifies the field number (from 1 to 255) that is queried in the current window. The function’s value returns true if the field is empty (string length is zero). A non-zero length string returns a value of false. If the specified field is the window’s active editing field (even though the window itself may not be active at the time), the function is performed on the field’s edited text. Otherwise, the function is performed on the field’s string. If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, FieldIsEmpty returns with a value of true. ------------------------------------------------------------ •• A new event type has been added (add to page 109). This event will be ignored by most applications. doPreRefresh (event) ~~~~~~~~~~~~~~~~ A window’s contents _may_ be refreshed (redrawn) before Tools Plus refreshes its own objects. Most applications will ignore this event. A doPreRefresh event is reported before each doRefresh event (which occurs when a window is completely or partially obscured, then becomes uncovered and needs to be redrawn). The doPreRefresh event lets your application draw or display objects before Tools Plus draws its own objects (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls). An example of the doPreRefresh event’s usefulness is if your application displays a picture as a background for a window. When your application receives a doPreRefresh event, it can draw the background picture only. The next time your application calls PollSystem, Tools Plus will refresh all its own objects and report a doRefresh event for your application to process. When a doPreRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed. Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing. Programming Considerations ~~~~~~~~~~~~~~~~~~~~~~ • When your application detects a doPreRefresh event, it should respond in the following manner: CurrentWindow(Poll.Window); {Make the affected window the } { current grafPort. } BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only} { within the area that needs } { refreshing (includes all } { monitors). } for theScreen:=1 to NumberOfScreens do {Repeat for each monitor } begin { in which the window appears. } BeginUpdateScreen(theScreen); {Drawing area reduced to the } { specified screen. } { …insert your color-dependent drawing code here… } EndUpdateScreen; {End the drawing for this } { monitor, and restore the } { window’s visible (drawing) } end; { region. } { …insert your color-independent drawing code here… } EndUpdate(WindowPointer(Poll.Window)); {End the update for the } { window. } CurrentWindowReset; {Reset the current window to be } { the same as the active window} { (optional command). } * BeginUpdate temporarily sets the window’s visRgn (visible region where drawing occurs) to the intersection of the visRgn and updateRgn (region requiring updating). This effectively restricts drawing to the area that needs updating. The affected area may include Tools Plus objects which are automatically refreshed the next time PollSystem is called. * If your application did not put anything in the window except buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls, it should ignore the doPreRefresh event. * It is possible that several windows will need to be refreshed simultaneously if, for instance, a closing window exposed three windows behind it. PollSystem reports a single doPreRefresh event (followed by a doRefresh event) each time it is called in the event loop, one event for each window that needs refreshing. * Unlike ordinary Macintosh applications, a doPreRefresh event is not generated when a window is first opened. * A doPreRefresh event is not generated for desk accessories, Dialog Manager dialogs, alerts, or Dynamic Alerts. These events are handled automatically. * When responding to a doPreRefresh event, your application should limit itself to activities that pertain only to refreshing the specified window. Do not create or modify user interface elements, open, close, or move windows. * Your application can easily do all its drawing in response to a doPreRefresh event, or a doRefresh event. If, however, your application wants to do some drawing in response to both events, you will need to get a copy of the affected window’s visRgn (visible region) while inside the BeginUpdate/EndUpdate structure (to determine the region that is affected by the doPreRefresh drawing). After you finish refreshing the window and you have called EndUpdate, invalidate the affected region by using InvalRgn. This will ensure that your application will redraw the necessary objects in response to the doRefresh event. Valid Polling Record Fields ~~~~~~~~~~~~~~~~~~~~~ Poll.Window ------------------------------------------------------------ •• A new event type has been added (add to page 178). This event will be ignored by most applications. doChgInField (event) ~~~~~~~~~~~~~~~~ Indicator that the contents of your application’s active editing field have been changed. The doChgInField event is reported whenever the active field in your application is altered, either through typing, cutting, pasting (including the use of the PasteIntoField routine), clearing, or undoing/redoing (using the Edit menu). Most applications will ignore this event. Valid Polling Record Fields ~~~~~~~~~~~~~~~~~~~~~ Poll.Window Poll.Field ------------------------------------------------------------ •• The following note has been added to the User Manual. It pertains to C programmers compiling the Tools Plus Demo application… IMPORTANT! Errors when compiling the Demo… At the time of this writing, Water’s Edge Software has made every effort to ensure that our demo application will compile successfully the first time. Unfortunately, Symantec C/C++ compilers have undergone a series of revisions and some inconsistencies have arisen between compiler versions. Fortunately, these differences are simple to resolve. If your compiler gives you an error that states “argument to function ‘x’ does not match prototype,” it indicates that Symantec has made a minor revision to that function’s prototype (in the error message, ‘x’ will be replaced by the function’s name). To correct this error, inspect the offending line in the source file, which is likely a line like: PenPat(&gray); and revise it to match the prototype in the related header file. In the example above, the correction is as simple as changing the line to: PenPat(gray); /* Remove ampersand (&) from the variable */ To date, all inconsistencies have been of this nature. We are sorry for the inconvenience these issues may cause you, and would like to offer our assistance if you have problems getting the demo compiled. See the “Technical Support” chapter for information on how to contact Water’s Edge Software for assistance.